Video Toaster 4.3/Video Toaster v4.3.iso/3.1/toasterall/arexx_examples/tpaint/tpaintarexx.doc

Text File | 1993-06-08 | 17KB | 504 lines

ToasterPaint ARexx Interface  6/93

Command Summary

In general, there are 4 groupings of action codes:  mouse, menu, button,
and 'other' - codes that have no direct 'normal intuition interface'
counterpart:

Mouse action codes are:

    Move x y
    Pend  x y  (pen down)
    Penu  x y  (pen up)

These work exactly as if the mouse (normal) pointer initiated the action.

Some of the more common button action codes are:

        Undo; performs an undo operation
        Scis; goes into scissors/cut-out-a-brush mode (Pend, Move and Penu action
        codes actually do the cut)
        Redo; does a 'repeat' or 'again'-type operation
        Prgb r g b; sets the paint color, 4-bit RGB values
        8rgb r g b; sets the paint color, 8-bit RGB values
        Drre; draw rectangles" mode
        Drci; "draw circles" mode
        Dotb; "dotty (vs. smooth) brush" mode

More Action Code Notes

"Rdit" and "Dith" action codes:  setup the dither modes.  Dither only
applies to Preview encoding.  (Current printer drivers only allow for 4
bits per r,g,b color component.) ToasterPaint uses "random" dither by
default.  The "Ugad" action code updates the user gadget display.  Many
options can be set (or toggled) before forcing the display to update.  The
display is not updated if there are any messages pending, which is the
usual case with ARexx, so the "Ugad" code offers a way to update the
display under "programmer control".

When using the file requester from ARexx, filenames and directory names are
set up with the "Dnam" and "Fnam" action codes (messages).  Directories are
actually "cd"d to when the "Dsel" action code is received.  The "Okls"
action code acts like the "load/save,rgb/framestore/brush" button on the
upper right side of the file requester.  It is used to actually begin the
file loading or saving operation.

Action  Code List

8rgb           paint color, 8 bit numbers, set bright white with "8rgb 255 255 255"
Aali           anti-alias toggle
Aaof       anti-alias OFF
Aaon       anti-alias ON
Al24       alloc 24-bit
Aoff           all modes off
Arof           always render - off
Aron       always render - on
Aroo       always render mode toggle

Babx       back box gadget, moves screens to back of display
Bcmo       brush color mode toggle
Bcop       copy brush
Bdel           delete brush
Blur           blur effect
Blu2       blur effect, mode 2, "heavier blur"
Boot       performs "keyboard file" "boot" codes
Bres           restore brush
Brgb       r,g,b background
Brt2           - standard brush type
Brt3           | brush
Brt4           \ brush
Brt5           / brush
Brt6           "squares"
Brt7           "circles"
Bsmf       "filled in freehand"...flood on, bsmooth...
Bsmo       "smooth-connected" std brush (vs. dotty-disconnected)
Bswa       swap the "swap brush"
Bsz1       standard brush size select
Bsz2       brush size 1
Bsz3       brush size 2
Bsz4       brush size 3
Bsz5       brush size 4
Bsz6       brush size 5
Bsz7       brush size 6
Bszl           brush size, one larger
Bszs       brush size, one smaller
Btog       brush shape toggle,flips btwn brush shapes
Bwpa       black and white palette for Preview

Cbx0       color box 0, palette color select
Cbx1       color 1
Cbx2       color 2
Cbx3       color 3
Cbx4       color 4
Cbx5       color 5
Cbx6       color 6
Cbx7       color 7
Cbx8       color 8
Cbx9       color 9
Cbxa       color 10
Cbxb       color 11
Cbxc       color 12
Cbxd       color 13
Cbxe       color 14
Cbxf       color 15(last "real" palette color)
Cbxg       'current/front/ color, left range color
Cbxh       'background/shadow' color, right range color
Cbxi       PAINT color (de-selects range front/back color)
Clbx       escape button, hires closebox
Clrs           CLeaR Screen
Coof       coords off
Coon       coords on
Coor       toggles coord flag
Cpic           Copy picture to swap screen
Ctrl           control tools/sliders on/off

Dela           delay on bottom of screen, before scroll
Delo           delay off
Depa       default palette
Dflt           load default files keyboard.txt and gadget.pic
Dir0           df0: directory selection for file requester
Dir1           df1: directory selection for file requester
Dir2           df2: directory selection for file requester
Dir3        RAM: directory selection for file reqeuster
Dir4        dh0: directory selection for file requester
Dirp           "/"  parent directory selection for file requester
Dirr           ":"  root directory selection for file requester
Dith           matrix dither toggle
Dlva         DeLiVer" a line of ASCII rgb's to ToasterPaint {n,line#,n(r g b)}  all
        parameters are ascii, for example, " 320  10   60 20 180 ..."        " #pts
            line#   60=1st red valu 120=green 180=blue"
Dlvb       "DeLiVer" a line of BINARY rgb's to ToasterPaint
                {n,line#,n(r.w,g.w,b.w)}
Dnam       dirname string
Dotb       single dot brush
Doty       dotty brush (vs. 'smooth')
Drar           ellipse
Drci           circle
Drln           line mode
Drre           rectangle
Drrf           filled rectangles (1x mode tools)
Dsel           directory selection
Dswa       Delete swap screen

Endm       end magnify mode
Exec        Execute an AmigaDOS command

Fa24       fail/quit if not in 24 bit rgb mode
Fbof       framestore load, left/rightside pixel blacken, - off
Fbon       framestore load, left/rightside pixel blacken, - on
Fboo       framestore load, left/rightside pixel blacken, mode toggle
Film           fill mode toggle
Fiof           fill mode off
Fion           fill mode on
Flix           Brush flip horizontal
Fliy           Brush flip vertical
Flof           Flood off
Flon           Flood on
Floo           Flood on/off
Flpx           any flip horizontal
Flpy           any flip vertical
Fnam       filename string
Font           Load Font file requester
Frbx       front box gadget
Fsel           file selection
Fu24       fail/quit if rgb mode, but no undo buffer

Grmo       grid mouse - use mouse to specify a 2 endpoints (rectangle)
Grof       grid off
Gron       grid-lock on
Grst           ## ## grid start x,y (upper left corner)
Grto           grid toggle on-off.
Grxy       ## ## grid size x, y
Gxdn       Grid X decrement
Gxup       Grid X 'up' - increment
Gxva       Grid X value 16 bit
Gydn       Grid Y decrement
Gyup       Grid Y 'up' - incr
Gyva       Grid y value 16 bit

Harr           toggle 1 way horizontal blend
Hvar       toggle button, 2 way h/v blend
Hvof       set 2 way blend gadget OFF
Hvsh       2 way gadget (blending) imagery reset
Hvst       2 way gadget (TxMap) imagery reset

Ke24       keep 24 bit buffers in between "selects" (from switcher)
Ksdn       down arrow scroll
Kslt           left arrow scroll
Ksrt           right arrow scroll
Ksup      up arrow scroll

Lo24          Load RGB file requester
Load       call up load requester (for file, or brush, or font)
Lobr       Load Brush file requester
Loco       load-composite - uses switcher/framestore directory for default

Magn       magnify gadget
Maxc       max buttons for blend center
Maxe       max for blend Edge
Maxw       max for TxMap amt
Meof       memory display - off
Meon       memory display - on
Meoo       memory display mode toggle
Midc       middle setting for blend center
Mide       middle setting for blend Edge
Midw       middle setting for TxMap amt
Minc       min buttons for blend center
Mine       min for blend Edge
Minw       min for TxMap amt
Move       x,y position
Mswa       Merge swap screen

Noef       no effect, turn off all effects

Okls           ok load/save button

Pale           turn on/off PALETTE tools
Pcca           print - cancel
Pcfe           print - "fewer" copies
Pcmo       print - "more" copies
Pcok       print - ok button; initiate printing
Pend       x,y pen down, big pic assumed
Penu       x,y pen up
Pick           turn on/off pick mode
Pixy           pick from x,y (in message - remote/arexx only)
Pmad       paint mode - add
Pman       paint mode - and
Pmcl       paint mode - clear (normal)
Pmco       paint mode - colorize
Pmdn       paint mode - darken
Pmln       paint mode - lighten
Pmor       paint mode - or
Pmso       paint mode - solid/normal
Pmsu       paint mode - subtract
Pmxo       paint mode - xor
Pot0           center blend slider setting pot
Pot1           edge blend slider setting pot
Pot5           TxMap amt, slider setting
Poth           shade hor pos, blend hotspot
Potv           shade ver pos, blend hotspot
Prfl           prop gadget for scrolling file/dir names,on file requester
Prgb       r,g,b paint (4 bit/Preview mode colors)
Prin           Print requester
Pro0       refresh blend sliders
Pro1       prop routines, handle 'auto increment by one'
Pro5       TxMap amt prop
Pund       Palette Undo

Quia           Quit - but ask with requester
Quit           Quit - return to switcher without unloading

Rang       range mode immediate, combo w/other paint modes
Rdit           flip random dither
Redo       again/redo button
Rema       Remap to new palette
Rotm       Brush rotation MINUS 90 degrees (counter-clock)
Rotp       Brush rotation PLUS 90 degrees
Rubi       simple rub thru on
Rubt       rub thru paint mode

Sa24       save 24-bit
Sabr           Save Brush
Saco       save-composite - render toaster-24 bit to a frame-store file
Sbru       source - brush image instead of paint color
Scis           scissors/cut gadget
Scof           scroll lock - off
Scon       scroll lock - on
Scoo       scroll lock mode toggle
Shar           toggle 1 way horizontal
Shcf           show composite OFF
Shco       show composite
Shof       shift off, for   locking rectangle->swap brush aspect ratio
Shon       shift on, for un-locking rectangle->swap brush aspect ratio
Shoo       show overscan
Shva       toggle button, 2 way h/v TxMap mode
Sizi           TxMap/sizing effect
Snap       'snap centered view'...keeps toaster hires pic centered
Snof       snap off
Spoh       hor pos - TxMap hotspot
Spov       ver pos - 2 way TxMap hotspot
Squt           ~ keyboard...super-quit...asks switcher for "unload from memory"
Srgb       source - rgb color instead of brush image (default)
Svar           toggle vertical TxMap mode
Swap       swap screens menu option

Tbbo       text button bold
Tbit           text button italic
Tbun       text button underline
Tdv1       toaster dv1 (1st frame buffer)
Tdv2       toaster dv2 (2nd frame buffer)
Tgof       toaster gadgets off (no render button)
Tgon       toaster-type gadget handling (default)
Toof       1x mode off
Toon       x mode on...this is for "hires display"
Tran           transparent on/off (menu item)
Trgb       r,g,b transparent
Trof           transparent background color off
Tron       transparent background color on
Tstr           text string gadget
Ttog           blend 2-way direction toggle
Tvar           data for text string (ascii)
Txbt           text tools select
Txdn       Tile X value, decrement
Txma       txmap mode immediate
Txup       Tile X 'up' - increment
Txva       Tile X value 16 bit << 4 (in increments of 1/16)
Tydn       Tile Y value - decrement
Tyup       Tile Y 'up' - increment
Tyva       Tile y value 16 bit << 4 (in increments of 1/16)

Ugad       redo user gadget (hires+hamtools) display, waits for rendering to finish
Undo       undo button

Varr           toggle vertical blend
Vwco       view composite - render to Toaster

Warp       (INTERNAL only) simple turn on TxMap
Wexp       whole screen expand...go "zoom", non-interlace, superbitmap
Wham       whole Preview screen re-do (from rgb data), re-displays entire Preview
            image
Whoo       whole screen toggle (1x/2x button's action code)
Wshr       whole screen shrink...go skinnier, interlace
Wtog       TxMap 2-way direction toggle


ToasterPaint acts as a 'server' with regards to ARexx.  ToasterPaint will
not issue calls to ARexx, since it doesn't have a "macro" capability.
Therefore all ARexx applications need to be run from 'outside' ToasterPaint
(e.g.  from a CLI).  The ARexx program should include the statement
"address DigiPaint".  However, the action code "Exec", which simply calls
the AmigaDos execute function, can be used to start up macros by including
the AmigaDos "run" command.

Example -

?    Exec run rx test.rexx

or

?    Exec run execute dostest.txt

The KEYBOARD FILE is named "ToasterPaint_Startup/keyboard.txt".  It is a
simple (edit-able) ascii file.  Each line contains a "raw key code", a
blank (space character), and an action code to occur when the key is
pressed.  Multiple lines (actions) can be "tied" to each key by having more
than one line per key in the keyboard shortcut file.  The action codes are
processed in the order that they appear in the file.Note that the action
codes for the ARROW KEYS are somewhat tied to the real-time Control Panel:
they either move the screen, or they move the magnify view, depending on
the mouse position.  The keyboard shortcut file also contains another type
of entry:  "BOOT" codes.  The are two "BOOT" code classes, "BOOT" and
"Boot".  "BOOT" codes only "happen" once, as the program is starting,
before any screens are opened.  They're used primarily to setup default
conditions.  "Boot" codes occur after the screens are opened, and every
time the program is re-entered from the switcher.



Examples - File Requester, Font Loading, Making Text Brushes, Painting
These examples can be executed as CLI/Shell command files.  Place the code
in a file named "testcode".  Then use the AmigaDOS command "execute
testcode".  Outline, with 1 pixel, a rectangle from 50,49 to 100,99

?    hey DigiPaint Drre
?    hey DigiPaint Dotb
?    hey DigiPaint 8rgb 160 160 160
?    hey DigiPaint Pend 50 49
?    hey DigiPaint Penu 100 99

Load a file named "DEF" from disk named "ABC:"

?    hey DigiPaint Load
?    hey DigiPaint DnamABC:
?    hey DigiPaint Dsel
?    hey DigiPaint FnamDEF
?    hey DigiPaint Okls; load font from file named "FONTS:TOPAZ/11"
?    hey DigiPaint Font
?    hey DigiPaint Dnam FONTS:TOPAZ
?    hey DigiPaint Dsel
?    hey DigiPaint Fnam11
?    hey DigiPaint Okls
?    hey DigiPaint Clbx

Put "dropshadow"ed text on picture;...by making a dark gray brush, pasting
it, then doing same with light gray.

?    hey DigiPaint 8rgb 80 80 80
?    hey DigiPaint TvarHello
?    hey DigiPaint Tstr
?    hey DigiPaint Pend 100 99
?    hey DigiPaint 8rgb 160 160 160
?    hey DigiPaint Tstr
?    hey DigiPaint Pend 98 97

ToasterPaint, being a true 24 bit rgb paint program, operates on every
pixel with (more than) 24 bit resolution.  Each red, green and blue
component is treated as an 8 bit quantity, with an additional 8 bits used
for blending.  ToasterPaint can be used as a rendering utility.  External
programs can generate 24-bit rgb data and send the data into ToasterPaint's
buffers.  The data can then be saved as rgb files, framestores, rendered to
a Toaster frame buffer, or otherwise processed.  The "Dlvb" action code
(explained further on in this section) is used for this.

The following examples are given in the format used for rexx scripts.
DRAWING LINES
Instead of the 'Drln' mode, it's best to use the "Bsmo" (connected
brushstroke) mode in order to draw lines.  Instead of
  'Drln'
  'Pend' 50 50
  'Penu' 100 100
it's better to use
  'Bsmo'
  'Pend' 50 50
  'Penu' 100 100
The ('Bsmo') "be smooth"/connected brushstroke mode will paint all of the
in-between positions, bt drawing a line between the starting ('Pend') and
ending ('Penu') brush positions.  'Drln' is fairly unusable from ARexx.
It's only available from ARexx for the sake of 'logical completeness'.

FRAMESTORE SAVE FILENAMES

The (minimal) "correct" way to save a framestore is with the following action codes:
    'Saco'
    'Fnam123.FS.Test'
    'Okls'

Note that the filename *must* be prefixed with "###.FS." if the switcher is
to recognize this framestore file.  If you do not include this string at
the beginning of a framestore filename, then the switcher will not be able
to load the file (although ToasterPaint still can).  Also, be sure not to
use duplicate frame numbers because the switcher will only recognize 1
framestore file per frame number.

PAINT COLOR

"Prgb"/DigiPaint(old) is for setting up a 12 bit paint color.
"8rgb"/ToasterPaint   is for setting up a 24 bit paint color.
For "Prgb r g b", each r,g,b value is a  4 bit number (0-15  range).
For "8rgb r g b", each r,g,b value is an 8 bit number (0-255 range).


SCANLINE INTERFACE

The 'Dlva' and 'Dlvb' action codes (commands) are similar.
'Dlvb' takes binary numbers (UWORDs) as parameters.
'Dlva' takes ascii (normal string) arguments.
'Dlva' is somewhat slower because of the ascii->binary (internal) conversion.  It's format
is:
   Dlva #pixels line# r g b r g b r g b r g b r g b ... r g b

'Dlvb' was designed to be a quick machine language interface for scan line
rendering.  (DigiView4 uses this exact same command to send it's image into
DigiPaint's "buffer".  DigiView and DigiPaint are two other NewTek
products.) The 'Dlvb' format looks something like:
  ULONG  'Dlvb'
  UWORD  nbr_pixels
  UWORD  line_nbr
  UWORD  red_0
  UWORD  green_0
  UWORD  blue_0
   --- "many" groups of red,green,blue values, 1 group per pixel
  UWORD  red_n
  UWORD  green_n
  UWORD  blue_n

Remember, the "r g b" numbers are 10bit values (range of 0-1023).  (Bright
white's rgb data would be "1023 1023 1023", not "15 15 15".)

Here's an example program...
---
/* "Dlva" test program, Arexx to DigiPaint interface ***************/

address 'DigiPaint' /* host name */

nlines = 128 /* # of lines to display */
row = 20     /* (starting) line #, used by the 'Dlva' message */
gray = 0

do nlines    /* for each of 128 lines */

             /* setup r,g,b values for current lines */
  r = gray
  g = gray
  b = gray

             /* setup 32 pixels on this row */
  msg$ = ''
  do 32
     msg$ = msg$ r g b
  end

             /* setup 320 pixels = 10 groups of 32 pixels */
  msg$ =  msg$ msg$ msg$ msg$ msg$ msg$ msg$ msg$ msg$ msg$

             /* send 'Dlva' msg to DigiPaint/ToasterPaint */
 'Dlva' '320' row msg$

gray = gray + 1024/nlines  /* rgb values range from 0..1023 */
row = row + 1              /* used by the 'Dlva' message */
end                        /* 128 lines of 'gray' */

return
/************************* end of program **************************/